로그 및 진행 상황 알림

로깅 및 진행 상황 알림은 구현이 간단하지만 MCP 서버를 사용할 때 사용자 경험에 큰 차이를 만듭니다. 장시간 실행되는 작업 중에 문제가 발생한 것인지 궁금해하는 대신 무슨 일이 일어나고 있는지 사용자가 이해할 수 있도록 도와줍니다.

Claude가 주제 조사나 데이터 처리와 같이 시간이 걸리는 도구를 호출할 때, 사용자는 일반적으로 작업이 완료될 때까지 아무것도 볼 수 없습니다. 도구가 작동 중인지 멈춤 것인지 알 수 없기 때문에 답답할 수 있습니다.

로깅 및 진행 상황 알림을 활성화하면, 사용자는 뒤에서 정확히 무슨 일이 일어나고 있는지 실시간 피드백을 받을 수 있습니다. 작업이 실행되는 동안 진행률 표시줄, 상태 메시지, 상세 로그를 확인할 수 있습니다.

작동 방식

Python MCP SDK에서 로깅 및 진행 상황 알림은 도구 함수에 자동으로 제공되는 Context 인수를 통해 작동합니다. 이 context 객체는 실행 중에 클라이언트에 상태를 다시 전달하는 메서드를 제공합니다.

@mcp.tool(
    name="research",
    description="Research a given topic"
)
async def research(
    topic: str = Field(description="Topic to research"),
    *,
    context: Context
):
    await context.info("About to do research...")
    await context.report_progress(20, 100)
    sources = await do_research(topic)
    
    await context.info("Writing report...")
    await context.report_progress(70, 100)
    results = await generate_report(sources)
    
    return results

사용할 주요 메서드는 다음과 같습니다:

context.info() - 클라이언트에 로그 메시지 전송
context.report_progress() - 현재 값과 총 값으로 진행 상황 업데이트

클라이언트 측 구현

클라이언트 측에서는 이러한 알림을 처리하기 위해 콜백 함수를 설정해야 합니다. 서버가 이러한 메시지를 발생시키지만, 사용자에게 어떻게 표시할지는 클라이언트 애플리케이션에서 결정합니다.

async def logging_callback(params: LoggingMessageNotificationParams):
    print(params.data)

async def print_progress_callback(
    progress: float, total: float | None, message: str | None
):
    if total is not None:
        percentage = (progress / total) * 100
        print(f"Progress: {progress}/{total} ({percentage:.1f}%)")
    else:
        print(f"Progress: {progress}")

async def run():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(
            read,
            write,
            logging_callback=logging_callback
        ) as session:
            await session.initialize()
            
            await session.call_tool(
                name="add",
                arguments={"a": 1, "b": 3},
                progress_callback=print_progress_callback,
            )

클라이언트 세션을 생성할 때 로깅 콜백을 제공하고, 개별 도구 호출 시 진행 상황 콜백을 제공합니다. 이를 통해 다양한 유형의 알림을 적절하게 처리할 수 있는 유연성을 얻을 수 있습니다.

표시 옵션

이러한 알림을 표시하는 방법은 애플리케이션 유형에 따라 다릅니다:

CLI 애플리케이션 - 터미널에 메시지와 진행 상황을 간단히 출력
웹 애플리케이션 - WebSocket, 서버 전송 이벤트 또는 폴링을 사용하여 브라우저에 업데이트 전송
데스크톱 애플리케이션 - UI에서 진행률 표시줄 및 상태 표시 업데이트

이러한 알림 구현은 완전히 선택 사항이라는 점을 기억하세요. 완전히 무시하거나, 특정 유형만 표시하거나, 애플리케이션에 적합한 방식으로 표시할 수 있습니다. 이들은 장시간 실행되는 작업 중에 무슨 일이 일어나고 있는지 사용자가 이해할 수 있도록 도와주는 순수한 사용자 경험 향상 기능입니다.